home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / graphics / dyewor.zip / DYEWORKS.DOC next >
Text File  |  1993-08-19  |  12KB  |  307 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.        DYEWORKS Version 1.01 - VGA Color Reduction
  9.        ===========================================
  10.  
  11.        The author's address:
  12.  
  13.               Stefan Reich
  14.               Bjoernsonweg 12e
  15.               22587 Hamburg
  16.               Germany
  17.               Tel: 0049 40 86 31 62 (if you happen to speak German)
  18.               CIS: [100117,1415]
  19.  
  20.        "Dyeworks 1.01" software is freely distributable as long as this
  21.        document accompanies the executable DYEWORKS.EXE. However, the
  22.        program may not be included in a commercial product without
  23.        written permission from the author.
  24.  
  25.        What is it?
  26.        -----------
  27.  
  28.        Dyeworks
  29.        - reduces true color bitmaps to VGA-suited 256 colors or to any
  30.          given number of colors
  31.        - shrinks pictures with anti-aliasing
  32.        - is F A S T!
  33.        - offers a variety of dithering processes for optimal results
  34.        - reads and writes PCX, Targa and DKBTrace (POV-Ray) dump format
  35.        - requires (almost) constant amounts of memory and time,
  36.          regardless of image size and contents
  37.  
  38.        How you use it
  39.        --------------
  40.  
  41.        Dyeworks is batch-driven. That is, all parameters needed are
  42.        supplied on the DOS command line. This makes it possible to
  43.        process many files in a row without further user interaction.
  44.  
  45.        The usage is:
  46.  
  47.                DYEWORKS <option> <option> <option> ...
  48.  
  49.        Options are:
  50.  
  51.        *General Options
  52.  
  53.        -h,-? or no option
  54.        Displays a help screen showing available options.
  55.  
  56.        -i<file>
  57.        Specifies the input file. Currently supported are PC Paintbrush
  58.        (PCX), Targa and DKB dump format. The file type also determines
  59.        the type of image data:
  60.  
  61.        .TGA: Targa-24, 24 Bit True Color Uncompressed
  62.        .DIS: DKBTrace Dump, 24 Bit True Color Uncompressed
  63.        .PCX: PC Paintbrush, 256 Colors out of 256,000 (for VGA display)
  64.  
  65.        -o<file>
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.        Specifies the output file. Its file type may be different from
  73.        the input file's type; if necessary, conversion is done.
  74.        If no output file is given, Dyeworks just reads and displays.
  75.        *Input and output file may not be identical!*
  76.  
  77.        +o
  78.        Tells Dyeworks to <o>verwrite the output file in case it already
  79.        exists. Without this option, Dyeworks will not change an
  80.        existing file.
  81.  
  82.        +d (the default)
  83.        Displays picture while converting, in case the following
  84.        conditions are met:
  85.        - a VGA adapter is detected,
  86.        - the picture is less or equal to 320 (width) * 200 (height)
  87.          pixels in size (no SVGA support so far, sorry), and
  88.        - there is no output file or it is written in PCX format.
  89.        As soon as the picture is complete, Dyeworks waits for a key to
  90.        be pressed. So if you want to convert multiple files
  91.        continuously, make sure to specify "-d"!
  92.  
  93.        -d
  94.        Disables graphical display.
  95.  
  96.        +q (quiet mode)
  97.        Disables text display. This option does NOT imply "-d".
  98.  
  99.  
  100.        *True color manipulations
  101.  
  102.        Any image data read by Dyeworks (regardless of the format) is
  103.        first converted into true color. Now the manipulations listed
  104.        below may be executed. The last step is either saving the true
  105.        color data into a Targa or dump file, or creating a palette for
  106.        PCX output.
  107.  
  108.        -s<factor> (factor=1-100)
  109.        Shrinks the picture isometrically:
  110.  
  111.            new width = old width / factor
  112.            new height = old height / factor
  113.  
  114.        The shrinking process doesn't just remove pixels from the
  115.        picture: any program could give you that! No, it performs anti-
  116.        aliasing by averaging each square that will be deflated to one
  117.        pixel of the final image.
  118.        One application of this feature is to receive a kind of anti-
  119.        aliasing different from the one DKBTrace does, in terms of
  120.        smoothing without introducing noise. To obtain this effect,
  121.        render a picture at, let's say, 1280x800, and shrink it down to
  122.        320x200. I know, it's an immense size, and you will especially
  123.        get problems with your hard disk space (if you don't use
  124.        SuperStor(TM) :-). For the start, you could try a resolution of
  125.        640x400. Rendering this will take a time comparable to that a
  126.        320x200 raytracing with "anti-alias"-option on would need.
  127.  
  128.        +m
  129.        Mirrors picture = swaps left and right.
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.        +vd +vc
  138.        These options concern the reduction from the 16 Million color
  139.        range DKBTrace produces to the 256,000 color range a (standard)
  140.        VGA adapter supports. This operation is supposed to precede a
  141.        VGA palette creation, but in the first step leaves a true color
  142.        image that could be saved as well (but who would want to do
  143.        so?). Anyway, here is how it works:
  144.        The option "+vc" simply cuts off the two least significant bits.
  145.        (A little bit of computer math: 16 Million = 3*8 Bits; 256,000 =
  146.        3*6 Bits.) To cut a long story short: "+vc" is bad for
  147.        gradients, but good for large areas of constant color, because
  148.        it prevents "-pd" dithering (if turned on) from trying to dither
  149.        a color a VGA card just isn't able to display.
  150.        "+vd" cuts off two bits also, but remembers the "error" it makes
  151.        by doing so, in order to correct this error with the next pixels
  152.        processed. (You have guessed it: This is known as "dithering"
  153.        :-)
  154.        Using "+vd" together with "-pd" (s.b., together they're
  155.        "DoubleDither") gives you the smoothest gradients you've ever
  156.        seen. Try it: Render DKBTrace's "LAMP.DAT" (this will take some
  157.        hours), and display the output using Dyeworks (this will take
  158.        some seconds).
  159.  
  160.        -v (default)
  161.        No color range reduction takes place.
  162.        This can mean several things:
  163.        - The true color picture remains unchanged.
  164.        - If "-pd" option is turned on, it will do all the dithering
  165.        work - AFTER the palette is chosen. One reason for the
  166.        superiority of DoubleDither is the fact that palette creation
  167.        takes place when most (or all) of the dithering work is already
  168.        done. This makes it possible to design a palette more closely
  169.        aligned to the picture's real needs.
  170.        - If "-pn" is turned on, the effect will be a cut-off similar to
  171.        the one "+vc" would do.
  172.  
  173.  
  174.        *PCX output
  175.  
  176.        -c<colors> (default: -c256)
  177.        Sets the maximum number of output colors. For example, if you
  178.        say "-c100", at least 156 palette entries will be left blank.
  179.        By the way, the palette will always be sorted by descending
  180.        frequency. (In other words: most popular colors first, least
  181.        popular colors last.) Thus, if a Windows graphics software cuts
  182.        off the last 16 entries it needs for itself, it won't do much
  183.        harm.
  184.  
  185.        -pd -pl -pn
  186.        These options influence the way the original picture's colors
  187.        are assigned to the new palette.
  188.        -pn seeks "nearest" available color (in the RGB cube).
  189.        -pd does so, too, but superposes a full dither that does not
  190.        "forget" any error it has made (see "-pd" section above).
  191.        -pl dithers also, but in a much more "sloppy" way. Only great
  192.        errors will affect other pixels.
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.        -e<max> (1-256, default: -e12)
  200.        Limits the error that is saved and transported. This prevents
  201.        "-pd" dithering from making bad things worse: e.g., if a much
  202.        too bright color had to be chosen, the next pixel would be much
  203.        too dark instead in order to correct the error made. (Usually,
  204.        this won't occur unless you limit the number of colors (s.a.).)
  205.        "-e12" means that any error beyond a distance of 12 true color
  206.        shades (=3 VGA shades, or three 64ths of the distance between
  207.        black and white) will be ignored.
  208.  
  209.  
  210.        Examples
  211.        --------
  212.  
  213.        C:>dyeworks -inicepic
  214.        Standard command to display true color pictures ("nicepic.tga"
  215.        in this case). Palette creation; single dither; no output file.
  216.  
  217.        C:>dyeworks -ilamp -olamp
  218.        Reads "lamp.tga", creates a palette, dithers, displays if
  219.        possible, and saves to "lamp.pcx".
  220.  
  221.        C:>dyeworks -ibigpic.dis -s4 -osmallpic.tga
  222.        Reads "bigpic.dis", shrinks it to a fourth, and writes to
  223.        "smallpic.tga". Displaying is not possible since no palette is
  224.        generated.
  225.  
  226.        C:>for %p in (pic1 pic2 pic3) do dyeworks -i%p.dis -o%p.pcx +vd
  227.        -d -q
  228.        This call uses DOS "for" command to process three images in a
  229.        row. "pic1.dis", "pic2.dis" and "pic3.dis" will be converted to
  230.        "pic1.pcx", "pic2.pcx" and "pic3.pcx", respectively.
  231.        DoubleDither is turned on. Text and graphic display are
  232.        disabled.
  233.        In a batch file, the line would look slightly different:
  234.        for %%p in (pic1 pic2 pic3) do dyeworks -i%%p.dis -o%%p.pcx +vd
  235.        -d -q
  236.  
  237.        C:>for %p in (anim*.dis) do dyeworks -i%p -o%p.pcx +vd -d -q
  238.        Converts all DKB dump files beginning "anim" in current
  239.        directory to files with same name but PCX extension. For
  240.        example, "anim001.dis" would be converted to "anim001.pcx". In
  241.        fact, in this case DOS would expand the command line like this:
  242.        C:>dyeworks -ianim001.dis -oanim001.dis.pcx +vd -d -q
  243.        To avoid problems with a filename containing two extensions,
  244.        Dyeworks automatically removes all but the last:
  245.        C:>dyeworks -ianim001.dis -oanim001.pcx +vd -d -q
  246.  
  247.        C:>dyeworks -imanycols.pcx -c128 -olesscols.pcx
  248.        Reads "manycols.pcx", creates a new palette with up to 128
  249.        colors, and writes to "lesscols.pcx". Note that if reading a PCX
  250.        file with no shrinking applied, "+vd" and "+vc" options are
  251.        ignored since color range already is 256,000.
  252.  
  253.        Error Levels
  254.        ------------
  255.  
  256.        Dyeworks returns an error level depending on successful
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.        completion or occurrence of errors. The error level can be
  264.        checked using DOS "if errorlevel" command. See MS-DOS user's
  265.        guide.
  266.        These are the codes:
  267.  
  268.         0  No Error
  269.         1  Help screen displayed
  270.         2  Could not understand command line
  271.         3  Out of memory
  272.         4  Input file is corrupt or does not exist
  273.         5  Could not write output file (bad directory, disk full?)
  274.  
  275.        Warranty
  276.        --------
  277.  
  278.        I, the author, hereby guarantee that Dyeworks is the cheapest,
  279.        fastest and best DKBTrace VGA postprocessor available. However,
  280.        if you find a program that produces better results in shorter
  281.        time, you will get your money back. Contact me, and I will send
  282.        you a cheque for 0.00 US-$ (or, if you like, 0.00 UK pounds, 0
  283.        Yen or any other currency :-). Joking apart, contact me, and I
  284.        will see what I can do for Dyeworks 2.0.
  285.  
  286.        Design Limits
  287.        -------------
  288.  
  289.        Minimum operating system:             MS-DOS 3.0
  290.        Minimum processor:                    80286 (Pentium is OK, too)
  291.        Minimum free DOS memory:              400,000-414,000 Bytes
  292.        Minimum graphics adapter for display: VGA
  293.        Maximum bitmap size before shrinking: 2048*76800
  294.        Maximum bitmap size after shrinking:  1024*768
  295.  
  296.        Revision history
  297.        ----------------
  298.  
  299.        1.01 Released three days later
  300.             - PCX output sped up
  301.             - bugfix: +o option
  302.               (no "X.0" version is bug free (see OS/2 2.0)!!!!)
  303.  
  304.        1.0  First version; distributed in CompuServe's Graphics
  305.             Developers+ Forum
  306.  
  307.        Have fun!